|
Eclipse Platform Pre-release 3.0 |
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectorg.eclipse.core.runtime.PlatformObject
org.eclipse.core.internal.jobs.InternalJob
org.eclipse.core.runtime.jobs.Job
Jobs are units of runnable work that can be scheduled to be run with the job
manager. Once a job has completed, it can be scheduled to run again (jobs are
reusable).
Jobs have a state that indicates what they are currently doing. When constructed,
jobs start with a state value of NONE
. When a job is scheduled
to be run, it moves into the WAITING
state. When a job starts
running, it moves into the RUNNING
state. When execution finishes
(either normally or through cancelation), the state changes back to
NONE
.
A job can also be in the SLEEPING
state. This happens if a user
calls Job.sleep() on a waiting job, or if a job is scheduled to run after a specified
delay. Only jobs in the WAITING
state can be put to sleep.
Sleeping jobs can be woken at any time using Job.wakeUp(), which will put the
job back into the WAITING
state.
Jobs can be assigned a priority that is used as a hint about how the job should
be scheduled. There is no guarantee that jobs of one priority will be run before
all jobs of lower priority. The javadoc for the various priority constants provide
more detail about what each priority means. By default, jobs start in the
LONG
priority class.
IJobManager
Field Summary | |
static IStatus |
ASYNC_FINISH
Job status return value that is used to indicate asynchronous job completion. |
static int |
BUILD
Job priority constant (value 40) for build jobs. |
static int |
DECORATE
Job priority constant (value 50) for decoration jobs. |
static int |
INTERACTIVE
Job priority constant (value 10) for interactive jobs. |
static int |
LONG
Job priority constant (value 30) for long-running background jobs. |
static int |
NONE
Job state code (value 0) indicating that a job is not currently sleeping, waiting, or running (i.e., the job manager doesn't know anything about the job). |
static int |
RUNNING
Job state code (value 4) indicating that a job is currently running |
static int |
SHORT
Job priority constant (value 20) for short background jobs. |
static int |
SLEEPING
Job state code (value 1) indicating that a job is sleeping. |
static int |
WAITING
Job state code (value 2) indicating that a job is waiting to be run. |
Fields inherited from class org.eclipse.core.internal.jobs.InternalJob |
BLOCKED |
Constructor Summary | |
Job(String name)
Creates a new job with the specified name. |
Method Summary | |
void |
addJobChangeListener(IJobChangeListener listener)
Registers a job listener with this job Has no effect if an identical listener is already registered. |
boolean |
belongsTo(Object family)
Returns whether this job belongs to the given family. |
boolean |
cancel()
Stops the job. |
void |
done(IStatus result)
Jobs that complete their execution asynchronously must indicate when they are finished by calling this method. |
String |
getName()
Returns the human readable name of this job. |
int |
getPriority()
Returns the priority of this job. |
IStatus |
getResult()
Returns the result of this job's last run. |
ISchedulingRule |
getRule()
Returns the scheduling rule for this job. |
int |
getState()
Returns the state of the job. |
Thread |
getThread()
Returns the thread that this job is currently running in. |
boolean |
isSystem()
Returns whether this job is a system job. |
void |
join()
Waits until this job is finished. |
void |
removeJobChangeListener(IJobChangeListener listener)
Removes a job listener from this job. |
protected abstract IStatus |
run(IProgressMonitor monitor)
Executes the current job. |
void |
schedule()
Schedules this job to be run. |
void |
schedule(long delay)
Schedules this job to be run after a specified delay. |
void |
setName(String name)
Changes the name of this job. |
void |
setPriority(int i)
Sets the priority of the job. |
void |
setRule(ISchedulingRule rule)
Sets the scheduling rule to be used when scheduling this job. |
void |
setSystem(boolean value)
Sets whether or not this job is a system job. |
void |
setThread(Thread thread)
Sets the thread that this job is currently running in, or null
if this job is not running or the thread is unknown. |
boolean |
shouldRun()
Returns whether this job should be run. |
boolean |
shouldSchedule()
Returns whether this job should be scheduled. |
boolean |
sleep()
Requests that this job be suspended. |
void |
wakeUp()
Resumes execution of the given job. |
Methods inherited from class org.eclipse.core.internal.jobs.InternalJob |
compareTo, toString |
Methods inherited from class org.eclipse.core.runtime.PlatformObject |
getAdapter |
Methods inherited from class java.lang.Object |
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait |
Methods inherited from interface org.eclipse.core.runtime.IAdaptable |
getAdapter |
Field Detail |
public static final IStatus ASYNC_FINISH
run(org.eclipse.core.runtime.IProgressMonitor)
,
done(org.eclipse.core.runtime.IStatus)
public static final int INTERACTIVE
IJobManager#getPriority
,
IJobManager#setPriority
,
run(org.eclipse.core.runtime.IProgressMonitor)
,
Constant Field Valuespublic static final int SHORT
IJobManager#getPriority
,
IJobManager#setPriority
,
run(org.eclipse.core.runtime.IProgressMonitor)
,
Constant Field Valuespublic static final int LONG
IJobManager#setPriority
,
run(org.eclipse.core.runtime.IProgressMonitor)
,
Constant Field Valuespublic static final int BUILD
IJobManager#getPriority
,
IJobManager#setPriority
,
run(org.eclipse.core.runtime.IProgressMonitor)
,
Constant Field Valuespublic static final int DECORATE
IJobManager#getPriority
,
IJobManager#setPriority
,
run(org.eclipse.core.runtime.IProgressMonitor)
,
Constant Field Valuespublic static final int NONE
IJobManager#getState
,
Constant Field Valuespublic static final int SLEEPING
run(org.eclipse.core.runtime.IProgressMonitor)
,
IJobManager#getState
,
Constant Field Valuespublic static final int WAITING
IJobManager#getState
,
Constant Field Valuespublic static final int RUNNING
IJobManager#getState
,
Constant Field ValuesConstructor Detail |
public Job(String name)
null
.
name
- the name of the job.Method Detail |
public final void addJobChangeListener(IJobChangeListener listener)
listener
- the listener to be added.public boolean belongsTo(Object family)
Clients may override this method. This default implementation always returns
false
. Overriding implementations must return false
for families they do not recognize.
true
if this job belongs to the given family, and
false
otherwise.public final boolean cancel()
false
if the job is currently running (and thus may not
respond to cancelation), and true
in all other cases.public final void done(IStatus result)
This method must not be called from within the scope of a job's run
method. Jobs should normally indicate completion by returning an appropriate
status from the run
method. Jobs that return a status of
ASYNC_FINISH
from their run method must later call
done
to indicate completion.
result
- a status object indicating the result of the job's execution.ASYNC_FINISH
,
run(org.eclipse.core.runtime.IProgressMonitor)
public final String getName()
null
.
public final int getPriority()
public final IStatus getResult()
null
if this
job has never finished running.public final ISchedulingRule getRule()
null
if this job has no
scheduling rule.
null
.ISchedulingRule
public final int getState()
public final Thread getThread()
null
if this job is not running or the thread is unknown.public final boolean isSystem()
true
if this job is a system job, and
false
otherwise.setSystem
public final void join() throws InterruptedException
Note that there is a deadlock risk when using join. If the calling thread owns a lock or object monitor that the joined thread is waiting for, deadlock will occur.
InterruptedException
- if this thread is interrupted while waitingILock
public final void removeJobChangeListener(IJobChangeListener listener)
listener
- the listener to be removed.protected abstract IStatus run(IProgressMonitor monitor)
The provided monitor can be used to report progress and respond to cancellation. If the progress monitor has been cancelled, the job should finish its execution at the earliest convenience.
This method must not be called directly by clients. Clients should call
schedule
, which will in turn cause this method to be called.
Jobs can optionally finish their execution asynchronously (in another thread) by
returning a result status of Job.ASYNC_FINISH
. Jobs that finish
asynchronously must indicate when they are finished by calling
the method Job.done
.
monitor
- the monitor to be used for reporting progress, or
null
if progress monitoring is not required.
ASYNC_FINISH
,
done(org.eclipse.core.runtime.IStatus)
public final void schedule()
This is a convenience method, fully equivalent to
schedule(0L)
.
public final void schedule(long delay)
Scheduling a job that is already waiting, sleeping, or running has no effect
public final void setName(String name)
null
.
name
- the name of the job.public final void setPriority(int i)
public final void setRule(ISchedulingRule rule)
rule
- the new scheduling rule, or null
if the job
should have no scheduling rulepublic final void setSystem(boolean value)
value
- true
if this job should be a system job, and
false
otherwise.isSystem
public final void setThread(Thread thread)
null
if this job is not running or the thread is unknown.
Jobs that use the Job.ASYNC_FINISH
return code should tell
the job what thread it is running in. This is used to prevent deadlocks
thread
- the thread that this job is running in.ASYNC_FINISH
,
run(org.eclipse.core.runtime.IProgressMonitor)
public boolean shouldRun()
false
is returned, this job will be discarded by the job manager
without running.
This method is called immediately prior to calling the job's run method, so it can be used for last minute pre-condition checking before a job is run. This method must not attempt to schedule or change the state of any other job.
Clients may override this method. This default implementation always returns
true
.
public boolean shouldSchedule()
false
is returned, this job will be discarded by the job manager
without being added to the queue.
This method is called immediately prior to adding the job to the waiting job queue.,so it can be used for last minute pre-condition checking before a job is scheduled.
Clients may override this method. This default implementation always returns
true
.
public final boolean sleep()
SLEEPING
state.
The job will remain asleep until either resumed or canceled. If this job is not
currently waiting to be run, this method has no effect.
Sleeping jobs can be resumed using wakeUp
.
public final void wakeUp()
|
Eclipse Platform Pre-release 3.0 |
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |